package com.googlecode.lightest.core

/**
 * Represents a domain-specific task to be performed in a test. ITask's are
 * typically owned by IDomainSpecificApi's.
 */
interface ITask {

    /**
     * Configures the task
     *
     * @param config        the configuration for this task. The Node tree may
     *                      also contain configuration information for any
     *                      parent and child tasks. If it does, this task
     *                      object may inspect, but should not mutate, any
     *                      Nodes it does not directly relate to.
     * @param prefs
     * @param env           the environment in which this task is to be
     *                      performed
     * @param parentResult  the result of performing the parent task. May be
     *                      null if this task has no parent.
     * @param dispatcher    the dispatcher that will be dispatching the task
     */
    void configure(TaskNode config, IPreferences prefs, ITestEnvironment env,
        ITaskResult parentResult, ITaskDispatcher dispatcher)

    /**
     * Returns the name of the task.
     */
    String getName()

    /**
     * Returns the abbreviated name of the task.
     */
    String getShortName()
    
    /**
     * Returns a user supplied description of the task instance, its purpose,
     * etc.
     */
    String getDescription()

    /**
     * Returns a generated description of the paremeters to the task, typically
     * which identifies how the task could be reproduced.
     */
    String getParams()

    /**
     * Performs the task in an environment, and returns the result. Tasks may
     * choose to use or ignore the results of their parent tasks.
     */
    ITaskResult perform()
}
